home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
X User Tools
/
X User Tools (O'Reilly and Associates)(1994).ISO
/
sun4c
/
archive
/
tcltk.z
/
tcltk
/
man
/
cat3
/
SplitList.3
< prev
next >
Wrap
Text File
|
1994-09-20
|
9KB
|
265 lines
Tcl_SplitList(3) Tcl Library Procedures
_________________________________________________________________
NAME
Tcl_SplitList, Tcl_Merge, Tcl_ScanElement,
Tcl_ConvertElement - manipulate Tcl lists
SYNOPSIS
#include <tcl.h>
int
Tcl_SplitList(_i_n_t_e_r_p, _l_i_s_t, _a_r_g_c_P_t_r, _a_r_g_v_P_t_r)
char *
Tcl_Merge(_a_r_g_c, _a_r_g_v)
int
Tcl_ScanElement(_s_r_c, _f_l_a_g_s_P_t_r)
int
Tcl_ConvertElement(_s_r_c, _d_s_t, _f_l_a_g_s)
ARGUMENTS
Tcl_Interp *_i_n_t_e_r_p (out) Interpreter to use for
error reporting.
char *_l_i_s_t (in) Pointer to a string with
proper list structure.
int *_a_r_g_c_P_t_r (out) Filled in with number of
elements in _l_i_s_t.
char ***_a_r_g_v_P_t_r (out) *_a_r_g_v_P_t_r will be filled
in with the address of
an array of pointers to
the strings that are the
extracted elements of
_l_i_s_t. There will be
*_a_r_g_c_P_t_r valid entries
in the array, followed
by a NULL entry.
int _a_r_g_c (in) Number of elements in
_a_r_g_v.
char **_a_r_g_v (in) Array of strings to
merge together into a
single list. Each
string will become a
separate element of the
list.
char *_s_r_c (in) String that is to become
Tcl 1
Tcl_SplitList(3) Tcl Library Procedures
an element of a list.
int *_f_l_a_g_s_P_t_r (in) Pointer to word to fill
in with information
about _s_r_c. The value of
*_f_l_a_g_s_P_t_r must be passed
to Tcl_ConvertElement.
char *_d_s_t (in) Place to copy converted
list element. Must con-
tain enough characters
to hold converted
string.
int _f_l_a_g_s (in) Information about _s_r_c.
Must be value returned
by previous call to
Tcl_ScanElement, possi-
bly OR-ed with
TCL_DONT_USE_BRACES.
_________________________________________________________________
DESCRIPTION
These procedures may be used to disassemble and reassemble
Tcl lists. Tcl_SplitList breaks a list up into its consti-
tuent elements, returning an array of pointers to the ele-
ments using _a_r_g_c_P_t_r and _a_r_g_v_P_t_r. While extracting the argu-
ments, Tcl_SplitList obeys the usual rules for backslash
substitutions and braces. The area of memory pointed to by
*_a_r_g_v_P_t_r is dynamically allocated; in addition to the array
of pointers, it also holds copies of all the list elements.
It is the caller's responsibility to free up all of this
storage by calling
free((char *) *_a_r_g_v_P_t_r)
when the list elements are no longer needed.
Tcl_SplitList normally returns TCL_OK, which means the list
was successfully parsed. If there was a syntax error in
_l_i_s_t, then TCL_ERROR is returned and _i_n_t_e_r_p->_r_e_s_u_l_t will
point to an error message describing the problem. If
TCL_ERROR is returned then no memory is allocated and
*_a_r_g_v_P_t_r is not modified.
Tcl_Merge is the inverse of Tcl_SplitList: it takes a col-
lection of strings given by _a_r_g_c and _a_r_g_v and generates a
result string that has proper list structure. This means
that commands like index may be used to extract the original
elements again. In addition, if the result of Tcl_Merge is
passed to Tcl_Eval, it will be parsed into _a_r_g_c words whose
values will be the same as the _a_r_g_v strings passed to
Tcl 2
Tcl_SplitList(3) Tcl Library Procedures
Tcl_Merge. Tcl_Merge will modify the list elements with
braces and/or backslashes in order to produce proper Tcl
list structure. The result string is dynamically allocated
using malloc(); the caller must eventually release the
space using free().
If the result of Tcl_Merge is passed to Tcl_SplitList, the
elements returned by Tcl_SplitList will be identical to
those passed into Tcl_Merge. However, the converse is not
true: if Tcl_SplitList is passed a given string, and the
resulting _a_r_g_c and _a_r_g_v are passed to Tcl_Merge, the result-
ing string may not be the same as the original string passed
to Tcl_SplitList. This is because Tcl_Merge may use
backslashes and braces differently than the original string.
Tcl_ScanElement and Tcl_ConvertElement are the procedures
that do all of the real work of Tcl_Merge. Tcl_ScanElement
scans its _s_r_c argument and determines how to use backslashes
and braces when converting it to a list element. It returns
an overestimate of the number of characters required to
represent _s_r_c as a list element, and it stores information
in *_f_l_a_g_s_P_t_r that is needed by Tcl_ConvertElement.
Tcl_ConvertElement is a companion procedure to
Tcl_ScanElement. It does the actual work of converting a
string to a list element. Its _f_l_a_g_s argument must be the
same as the value returned by Tcl_ScanElement.
Tcl_ConvertElement writes a proper list element to memory
starting at *_d_s_t and returns a count of the total number of
characters written, which will be no more than the result
returned by Tcl_ScanElement. Tcl_ConvertElement writes out
only the actual list element without any leading or trailing
spaces: it is up to the caller to include spaces between
adjacent list elements.
Tcl_ConvertElement uses one of two different approaches to
handle the special characters in _s_r_c. Wherever possible, it
handles special characters by surrounding the string with
braces. This produces clean-looking output, but can't be
used in some situations, such as when _s_r_c contains unmatched
braces. In these situations, Tcl_ConvertElement handles
special characters by generating backslash sequences for
them. The caller may insist on the second approach by OR-
ing the flag value returned by Tcl_ScanElement with
TCL_DONT_USE_BRACES. Although this will produce an uglier
result, it is useful in some special situations, such as
when Tcl_ConvertElement is being used to generate a portion
of an argument for a Tcl command. In this case, surrounding
_s_r_c with curly braces would cause the command not to be
parsed correctly.
Tcl 3
Tcl_SplitList(3) Tcl Library Procedures
KEYWORDS
backslash, convert, element, list, merge, split, strings
Tcl 4
